feat: GroupKeyHolder for GMS key management by moudyellaz · Pull Request #449 · logos-blockchain/logos-execution-zone

moudyellaz · 2026-04-15T22:19:02Z

🎯 Purpose

This PR adds GroupKeyHolder to the wallet for group-owned private PDAs. A group of controllers shares a Group Master Secret (GMS). From it, each controller independently derives identical keys for any PDA the group owns, enabling private multisig and k-of-n patterns over existing PDA-based programs without changing those programs.

⚙️ Approach

key_protocol: GroupKeyHolder (core cryptography)

Per-PDA key derivation via SHA256(domain_prefix || gms || pda_seed) producing NSK/NPK/VSK/VPK through the existing derivation chain.
epoch counter + ratchet(rotation_salt) forward-hashes the GMS so removed members cannot derive future keys.
seal_for(recipient_vpk) / unseal(sealed, own_vsk) encrypts GMS+epoch via ephemeral ECDH + domain-separated KDF + AES-256-GCM for distribution over untrusted channels.
Debug impl redacts GMS, raw accessor named dangerous_raw_gms to flag intent.

key_protocol: NSSAUserData storage

group_key_holders: BTreeMap<String, GroupKeyHolder> field with #[serde(default)] for backward compatibility.
group_pda_accounts: BTreeMap<AccountId, Account> local cache for decrypted group PDA state.
get_group_key_holder / insert_group_key_holder accessors.

wallet: mask-3 transaction construction

PrivateGroupPda { group_label, program_id, seed } variant on PrivacyPreservingAccount.
group_pda_preparation derives keys from GroupKeyHolder, computes AccountId::for_private_pda, reads PDA state from local cache.

Test program: `group_pda_spender`

Handles deposit (claim + balance transfer) and spend (direct balance modification + noop chained call for mask-3 binding).
Unit tests in nssa/src/state.rs verify both paths at the circuit level.

Integration test

Demonstrates GMS sealed distribution, key agreement, and forward secrecy after ratchet.

🧪 How to Test

RISC0_DEV_MODE=1 cargo test --release -p key_protocol
RISC0_DEV_MODE=1 cargo test --release -p nssa -- group_pda

🔗 Dependencies

PR feat: private PDA support in the privacy circuit #446 (private PDA circuit support) — merged.

📋 PR Completion Checklist

Complete PR description
Implement the core functionality
Add/update tests
Add/update documentation and inline comments

…seal/unseal

Pravdyvy

Thank you for PR. Left a couple of questions.

Pravdyvy

lgtm

schouhy

Thanks for the PR. Leaving some thoughts while I finish reviewing

Arjentix

Thanks for the PR. Left some small comments.

I didn't quite get how it works, probably more examples like k/nsignatures program and an integration test demonstrating it would be nice

moudyellaz · 2026-04-29T09:07:37Z

group_pda_spender in test_program_methods/ is the example program. A full integration test that covers deposit → spend requires membership proof resolution for existing private PDAs, which the wallet doesn't support for group PDAs yet. The unit tests in circuit.rs verify both paths at the circuit level. A more complete integration test will follow once the wallet can resolve group PDA membership proofs. @Arjentix

…6-0113

schouhy

Hey thanks. Have some general comments about the approach

- Add SealingPublicKey/SealingSecretKey type aliases for seal_for/unseal - Generalize PrivateGroupPda to PrivatePda with pre-resolved keys - Rename group_pda_spender to private_pda_spender - Rename group_pda_accounts to pda_accounts with serde alias - Remove unused storage_mut() - Remove stale group_pda_router.bin artifact

schouhy

Thanks LGTM. I'd personally remove the epoch, ratcheting and change the private_pda_spender to use the authenticated transfer. But I don't insist.

moudyellaz force-pushed the moudy/feat-group-key-holder branch 2 times, most recently from 12ef35b to 4938373 Compare April 17, 2026 15:02

Base automatically changed from moudy/feat-private-pdas to main April 22, 2026 22:34

moudyellaz force-pushed the moudy/feat-group-key-holder branch from 9822584 to 1fdc2da Compare April 22, 2026 22:54

moudyellaz marked this pull request as ready for review April 22, 2026 23:33

moudyellaz requested review from Arjentix, Pravdyvy and schouhy April 22, 2026 23:33

moudyellaz added 4 commits April 27, 2026 02:43

feat: add GroupKeyHolder with per-PDA derivation, epoch ratchet, and …

f321560

…seal/unseal

feat: add GroupKeyHolder storage and PrivateGroupPda wallet variant

48f95b1

feat: add group PDA test program, unit tests, and integration test

5b9cf95

fix: rebuild artifacts

636fc9d

moudyellaz force-pushed the moudy/feat-group-key-holder branch from 58cf9ef to 636fc9d Compare April 27, 2026 00:46

moudyellaz removed request for Arjentix, Pravdyvy and schouhy April 27, 2026 00:48

moudyellaz force-pushed the moudy/feat-group-key-holder branch from f8fd4c8 to 6504d1f Compare April 27, 2026 01:24

moudyellaz requested review from Arjentix, Pravdyvy and schouhy April 27, 2026 07:47

Pravdyvy reviewed Apr 27, 2026

View reviewed changes

Comment thread integration_tests/tests/group_pda.rs Outdated

Comment thread key_protocol/src/key_management/group_key_holder.rs

Comment thread key_protocol/src/key_management/group_key_holder.rs

fix: rebuild artifacts

9927e6e

moudyellaz force-pushed the moudy/feat-group-key-holder branch from 6504d1f to 9927e6e Compare April 27, 2026 12:43

Pravdyvy approved these changes Apr 27, 2026

View reviewed changes

schouhy reviewed Apr 28, 2026

View reviewed changes

Comment thread nssa/src/state.rs Outdated

Comment thread key_protocol/src/key_management/group_key_holder.rs Outdated

Comment thread nssa/src/state.rs

Comment thread key_protocol/src/key_protocol_core/mod.rs Outdated

Arjentix reviewed Apr 28, 2026

View reviewed changes

refactor: address PR #449 review feedback

198eac1

moudyellaz requested review from Arjentix and schouhy April 29, 2026 12:41

Arjentix approved these changes Apr 29, 2026

View reviewed changes

moudyellaz added 3 commits April 29, 2026 14:54

fix: fmt

460d7e7

fix: bump testcontainers to resolve RUSTSEC-2026-0112 and RUSTSEC-202…

2764956

…6-0113

merge: resolve Cargo.lock conflict with main

c327f59

schouhy reviewed Apr 29, 2026

View reviewed changes

moudyellaz requested a review from schouhy April 30, 2026 07:25

schouhy approved these changes Apr 30, 2026

View reviewed changes

moudyellaz added 3 commits April 30, 2026 15:04

fix: resolve merge conflicts

4c28133

fix: rebuild artifacts

b9ceda9

fix: remove epoch and ratcheting, fix PDA identifier

4690ca5

Conversation

moudyellaz commented Apr 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🎯 Purpose

⚙️ Approach

key_protocol: GroupKeyHolder (core cryptography)

key_protocol: NSSAUserData storage

wallet: mask-3 transaction construction

Test program: group_pda_spender

Integration test

🧪 How to Test

🔗 Dependencies

📋 PR Completion Checklist

Uh oh!

Pravdyvy left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Pravdyvy left a comment

Choose a reason for hiding this comment

Uh oh!

schouhy left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Arjentix left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

moudyellaz commented Apr 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

schouhy left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

schouhy left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

moudyellaz commented Apr 15, 2026 •

edited

Loading

Test program: `group_pda_spender`

moudyellaz commented Apr 29, 2026 •

edited

Loading